ClockPop Skins For ClockPop 2.7
c. Stephen Millman 2001
Freeware


This program creates "Skin" files to change the presentation of various features of ClockPop (a freeware hack).  If you do not have ClockPop on your handheld, ClockPop Skins may not work properly.


I. Overview

ClockPop Skins lets you modify the information ClockPop presents in the "Battery" (upper left) and "Memory" ( upper right) portions of the screen, provided that you have turned the Battery and Memory information items on in ClockPop itself.

 You can also  set the font this information appears in and the "long names" used by ClockPop for the days of the week, determine whether the date is at the top or the bottom and control what information appears in the appointment list (and in what order).

ClockPop Skins creates "SKIN" files of two types--the current active Skin file and other inactive skin files you can substitute for the current skin file, called "XSkins" in the program.

ClockPop will function with no Skin files, so you do not need to install ClockPop Skins to use ClockPop.
II. Details
A. Start up
1. First Time
The first time you start ClockPop Skins, it will create a new Skin file and ask you to name it.
2. In General
The main screen is for changing the messages that appear in the "Battery Info" area (the upper right) and the "Memory Info" area (upper left) of the ClockPop display if ClockPop is configured to show "Battery Info" and "Memory Info" respectively.  Along the top is a push button that shows whether you are dealing with the right or left message.  Below are three lists of "functions" you can use in creating the content to be displayed in this area.  Below that are three buttons, "Save" (used to save your changes), "Test" (used to test your changes) and "Clear" (used to clear the current text).  To the right of the buttons is a display showing how the current instruction list will display.  Underneath the buttons is the current instruction list itself.


B. Modifying the Messages
1. In General
To modify the message to be displayed by ClockPop as the Battery Info or Memory Info, first select the correct area ("Right" or "Left") then change the content as described below.  Then (if you want) change the font, as described below.  Test and, if you like it, save.

2. Content
The content ClockPop will display is controlled by the "instruction string."  ClockPop Skins displays the instruction string as text at the bottom of the screen.  The instruction string may at first seem a little strange, but it is actually very simple-any text not in between a "[" character and a "]" character is just displayed as you see it.  Any text inside these two characters calls a function which produces text to be displayed.

For example, the default Battery Info instruction is
Battery:
[VOLTAGE]V ([PERCENT]%)
which produces the word "Battery:" on the first line and a second line with the voltage, followed by a "V" followed by a space and a "(" character followed by the percentage of the battery left, followed by a "%" character and the ")" character.


The available functions are entered into the instruction string by first putting the insertion point where you want the function, and then tapping the function list to enter the function.  The available functions are:
               a. [VOLTAGE]-the current battery voltage to two decimal places (there is no units indicator-you need to add the "V" if you want it)
               b. [PERCENT]-the current battery percent (there is no "%" indicator, you need to add it if you want it)
               c. [WARNAT]-the voltage at which the PDA will warn you the battery is low (there is not units indicator, you need to add the "V" if you want it) 
               d. [OFFAT]-the voltage at which the PDA will shut of the screen and other user controlled operations (there is not units indicator, you need to add the "V" if you want it)
               e. [CHARGING]-shows either "On AC" or "On Battery"
               f. [CARDFREE]-shows number of KB free memory on the internal card.  (You need to add the " KB" if you want it in the display).
               g. [CARDSIZE]-total memory on the internal card (also in KB but without the units indicator unless you add it)
               h. [HEAPFREE]-free space in the system heap (in KB, not indicated).  (The PalmOS uses the card for two purposes, most is storage (sort of like a hard disk) and smaller, fixed part (250 KB on OS 4.0) called the "heap" is set aside for program use (sort of like a PC's "memory").  If you run out of room in the heap, you crash
                i. [HEAPSIZE]-the total size of the heap (used and unused space) (in KB, not indicated)
                j. [HEAPLARGEST]-the largest contiguous free block of memory in the heap (in KB, not indicated).  If a program request more heap space for a single operation than this, the PDA will crash.
                k. [CARDPCT]-percentage of the card that if free ("%" not indicated).
                l.  [HEAPPCT]-percentage of the heap that is free ("%" not indicated).
                m.[TIME]-the current time plus or minus a specified number of minutes.  (It you select this from the function list, you will be prompted to enter the offset.)  This appears in the instructions as, for example, [TIME-300] which means five hours earlier than the present time.  [TIME] is useful for showing the time in another city.  For example, I live in New York but often talk to people in London, so I put in my Memory Info area the word "London:" and the time in London, [TIME300]
                n. [XTERN]-XTERNs are a way of adding functionality to ClockPop.  An XTERN is a separate file that ClockPop will call to get the text put display in this spot.  When you tap the XTERN function in the list, it will present a dialog-tap the "Select XTERN button for a list of available XTERNS, select the one you want and fill in the needed information.  Then press OK. 

ClockPop Skins comes with a group of XTERNs.  The details of these XTERNS and instructions for writing additional ones are in another file.
                     
3. Display font
ClockPop Skins will also let you change the font in which the message is displayed-there is a font menu.  The Save button saves both the instruction list and the current font.

C. Modifying long day names
ClockPop Skins can also be used to modify "long" day names.  The PalmOS supplies localized short day names but doesn't really use long ones, so when ClockPop displays long names, it uses the English names I gave it.  There is a menu item that lets you change the names for a given skin. 



D. Setting the Location of the Date
The menu item "Set Date Location" lets you choose between date at bottom (with up to 4 appointments displayed) and date at top in the title bar (with up to 5 appointments displayed).
E. Appointment Preferences



This dialog lets you set which appointments are ignored by ClockPop ("hidden") and which are treated as special by ClockPop.  In addition, you can control the order in which various types of appointments are displayed.

"Hide if event begins with any of:" lets you define when ClockPop should ignore an appointment--if the text of the appointment begins with any of the characters you specify, ClockPop will ignore the event.

"Specials  begins with any of:" lets you define when ClockPop will treat an event as special.  (By default, ClockPop lists Special Events first.  You can change the behavior in the area marked "Show" on this page).  If the text of any appointment begins with any of the characters you specify, ClockPop will treat is as a Special Event.

"Show" lets you control the order in which appointments are listed.  By default, ClockPop lists Timed Special appointments, followed by Untimed Special appointments, followed by other Timed appointments, followed by other Untimed appointment.  
Tap the triggers below to specify a different order.  (You don't have to tell ClockPop whether you mean all Timed (or all Untimed) or other Timed (or Untimed), it determines this by whether the corresponding  Special events have been previously shown.
F. Power Off Method
This menu item set the way in which ClockPop tells the PDA to go back to sleep if you woke it by invoking ClockPop.  ClockPop  now uses the official, correct, Palm-approved method.  So it should not cause problems in most newer PDAs.  Previous versions of ClockPop used an undocumented method that Palm now tries to hide from prying eyes.  The only problem is that the new method does not work on all Palms.  Some Handspring models do not seem to respond to the Palm-approved method.  This preference lets you use the old, undocumented method that worked fine on the Handspring models.
G. Working With Skins
The Skins menu lets you create a new skin, change the current skin, delete an inactive skin and rename the current skin.

